API Common References

HTTP Status Codes:

Success codes

200 OK: Successful request, typically used for GET and PUT operations.

201 Created: The request has been fulfilled, and a new resource has been created, often used for POST operations.

204 No Content: The request was successful, but there is no response body (usually for successful DELETE operations).

Error codes

400 Bad Request: The client's request is malformed or invalid.

401 Unauthorized: Authentication is required or has failed.

403 Forbidden: The client does not have permission to access the requested resource.

404 Not Found: The requested resource does not exist.

405 Method Not Allowed: The HTTP method used is not allowed for the requested resource.

500 Internal Server Error: An unexpected error occurred on the server.

503 Service Unavailable :

504 Gateway Timeout:

Versioning

Vesioning in a RESTful API is the practice of providing different versions of your API to accommodate changes and ensure backward compatibility. There are various approaches to versioning, including versioning in the URL, headers, or request parameters. Navida pro implements versioning for Spring Boot REST API using the URL approach.

Versioning in the URL:

In this approach, you include the version number in the URL path. There are two common ways to format the URL:

Using the v prefix: You can prefix the version number with a 'v', like /v1/resource. This is a straightforward and widely adopted approach.

@RestController
@RequestMapping("/v1/resource")
public class ResourceControllerV1 {
    // Controller logic for version 1
}

Response Body Structure

{
  "status": "success",
  "message": "Request processed successfully",
  "data": {},
  "error": {
    "code": "ERR-001",
    "message": "An error occurred while processing the request",
    "httpStatus": 500
  }
}

guidelines

Use Nouns in Resource URIs:

Use nouns (not verbs) to represent resources in the URI. For example, use /users instead of /getUsers.

Use HTTP Methods Properly:

Use HTTP methods (GET, POST, PUT, DELETE, etc.) according to their intended purposes. For example, use GET for read operations ( no BODY is alloweded), POST for creating resources ( Should have a body), PUT for updating resources, and DELETE for deleting resources.

Use Plural Nouns for Resource Names:

Use plural nouns for resource names to represent collections. For example, /users for a collection of user resources.

Version Your API:

Include a version number in the API URL to ensure backward compatibility as your API evolves. For example, use /v1/users for version 1 of the users resource.

Use Meaningful Status Codes:

Use appropriate HTTP status codes to indicate the result of each API request (e.g., 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error, etc.).

Provide Clear and Consistent Error Messages:

When an error occurs, provide clear and detailed error messages in the response body along with the appropriate HTTP status code.

Implement Pagination for Large Collections:

If your API returns large collections of resources, implement pagination using query parameters (e.g., ?page=1&per_page=10) to limit the number of items returned in a single response.

Use Filters, Sorting, and Searching:

Allow clients to filter, sort, and search for resources using query parameters (e.g., ?filter=..., ?sort=..., ?q=...).